/**
*  \file sections.h
*
*  \brief
*
*  \author   <@linde-mh.de>
*
*
*/

#ifndef SECTIONS_H_INCLUDED
#define SECTIONS_H_INCLUDED

#ifndef SECTIONS_LINKAGE
#define SECTIONS_LINKAGE extern
#endif

/*================================================[ public includes  ]================================================*/
#include "../cfg/prj.h"
#include "../list/list.h"

/*================================================[ public defines   ]================================================*/

/*================================================[ public datatypes ]================================================*/


struct section_data
{
   U32 address;
   U32 size;
   U32 size_max;
   U8 data[];
};


LIST_NODE_STRUCT( section ,struct section_data);

LIST_HEAD_STRUCT( section_list, struct section);


#define SECTION_DATA( section ) LIST_DATA( section )


/*================================================[ public variables ]================================================*/

/*================================================[ public functions ]================================================*/

/**
 * Initialize a new section_list.
 *
 * \return  A pointer to the new section_list or NULL, if it could not be created.
 */
struct section_list* section_list_create();

/**
 * Initialize a new (empty) section with a certain capacity (maximum size). When this function finishes, the section
 * will not contain any data, but the reserved space will be 'capacity' bytes.
 *
 * \param   capacity  The maximum size of the new section
 * \return  A pointer to the new section_list or NULL, if it could not be created.
 */
struct section* section_create(U32 capacity);

/**
 * Delete a section list and all sections that it contains and release all occupied memory.
 *
 * \param   seclist  The section list which should be deleted.
 */
void section_list_delete(struct section_list* seclist);

/**
 * Delete a section and release all occupied memory. If the section is part of a section list, it will be unlinked from
 * the list before deletion.
 *
 * \param   sec   The section that is supposed to be deleted.
 */
void section_delete(struct section* sec);

/**
 * Remove all sections from the section list and free their memory. This does not delete the 'seclist' itself.
 */
void section_list_clear(struct section_list* seclist);

/**
 * Inserts a section to a section list.
 */
void section_insert(struct section_list* seclist, struct section* sec);

/**
 * This function sorts all the sections in 'seclist' by ascending start addresses.
 */
void sections_sort( struct section_list *seclist);

/**
 * Fills/Overwrites all sections in the section list with a fill byte.
 */
void sections_fill(struct section_list* seclist, U8 fillByte);

/**
 * This function removes all the sections from 'seclist' which don't lie within a section in 'bounds'. If a section from
 * 'seclist' partially lies outside the bounds, the part of the section that lies outside is deleted.
 */
void sections_enforce_bounds(struct section_list* seclist, struct section_list* bounds);

/**
 * This function iterates over the boundary list and joins all sections from 'seclist', which lie in the same boundary
 * section. If 'boundaries' is NULL, it simply joins all sections in the 'seclist'. \n
 * 'Joining' sections means that the content of two (or more) sections is copied into a single large section and the
 * undefined memory regions between the sections are filled with the 'fillByte'.
 */
RC sections_maximize(struct section_list* seclist, struct section_list* boundaries, U8 fillByte, BO minimalFill);

/**
 *
 */
void* sections_dump(struct section_list* seclist , U8 padding, U32 start_address, U32 size, void* data);

/*====================================================================================================================*/

#endif

/***********************************************************************************************************************
*                             Copyright 2010 Linde Material Handling. All rights reserved.                             *
***********************************************************************************************************************/
